Software Document Automation:
A Technical Overview
1.0 Introduction
Documentation is an integral part of the software-development
process. Software documentation is an organized collection of
written materials that help people understand the software's:
- Requirements
- Behavior
- Design
- Code structure
- Test history
- Development trade-offs
Therefore, software documentation tends to be closely coupled with
information in the software-engineering tools that addresses these
areas.
Software developers in many industries produce software
documentation, either for internal use or for customers as a
deliverable. In some cases, software documentation is used to prove
conformance to externally imposed safety, certification, or
regulatory standards.
Analysis and design tools, programming environments, and testing
tools are some of the many software-development tools used that
contain information that can become part of software
documentation. For example, the programming environment may
contain information about the code that defines the names and
number of sections in a document. Tools may also contain graphics
and text that can be included in the documentation. The software-development tools, however, seldom contain all of the information
necessary for the documentation. Explanations and other annotations
usually must be added to the final documentation.
If you need to create software documentation automatically and
flexibly while maintaining consistency with your software-development tools and processes, SoDA(TM) is your solution.
SoDA's unique capabilities provide you with automatic extraction of
the information present in the software-engineering tools, while
giving you a high degree of flexibility in customizing your documents
and maintaining their consistency with the software-engineering
tools.
SoDA makes good software documentation easier to create and
maintain. Its unique approach preserves the advantages--and
eliminates the disadvantages--of traditional approaches.
2.0 Traditional Approaches to Software Documentation
The Manual Approach
Producing software documentation manually often results in
inconsistent and incomplete documents be-cause engineering
information is always changing during the course of software
development. Furthermore, manual documentation is very labor
intensive and error-prone. As the complexity of software grows,
organizations have an increasing need to automate and consistently
maintain software documentation that captures the entire
software-development process.
The manual process for documenting software normally begins with
writing text from scratch or cutting and pasting information from
software-engineering tools. To ensure that the document is correct
in form and content, you or others review the document and then edit
it, repeating this cycle until publication.
Manual document production has the advantage of being flexible,
because you have complete control over the document's appearance
and content. However, this process quickly becomes overwhelming
because it provides no tool support for incorporating information
from other sources such as software-engineering or CASE tools.
When the information from engineering tools changes, you must
manually insert sections of the document and/or cut-and-paste from
the tools to the document. Not only is this process very laborious,
but you have no way of knowing when you need to make changes to
your document, because there are no automated consistency checks
between the document and engineering tools. Therefore, your
document quickly becomes inconsistent with the software.
The Conventional Automated Approach
Conventional document generators attempt to solve the problems of
the manual approach by automatically pulling text and graphics from
tools that address software requirements, analysis, design, code,
tests, and so on. The conventional automated documentation process
begins with generating the document's text as a batch process
guided by templates. As before, you or other reviewers evaluate the
document for correctness and then you edit it for final form.
Conventional tools for automated document generation appear to
reduce the effort required to produce documents because they reduce
reliance on cut-and-paste operations and enforce standard formats.
However, they also introduce a new set of problems:
- The document generator generally works with only one particular
engineering tool. It does not address the entire lifecycle.
- Information required by the document that would not otherwise
be in the software-engineering tool must be embedded. This means
that you must author your document in the engineering tools, using
only text editors that the tool provides--a fragmented authoring
process that forfeits the advantages of a document publishing tool.
- Templates are specified through programming or mark-up
language and are hard to modify. Documents are difficult and
expensive to tailor.
- Edits made in the generated documents are lost the next time you
generate the document, requiring additional effort to keep
documents in synch with engineering tools.
Consequently, the flexibility of the manual approach is lost because
control over the document content and appearance resides in the
generation tool, not in the document. Furthermore, your document
easily becomes outdated because it is too laborious to both
regenerate and reedit every time the software changes.
3.0 SoDA's Documentation Process
Pushing the Boundaries of Traditional Approaches
Although manual and conventional automated approaches to software
documentation each have advantages, they also have disadvantages
that are largely prohibitive to implementing a high-quality,
efficient documentation process that covers the entire lifecycle.
While the manual approach is flexible, but not automated, the
conventional automated approach forfeits flexibility in favor of
automation. With SoDA, you don't have to choose.
The engineering tools used throughout the software-development
cycle contain relevant information that becomes a major part of
software documentation. In fact, software documents often have
structures that mirror information in the engineering tools. For
example, nested document sections are often used to document
nested design components. The engineering tools may also contain
graphics and text that should be included in the document as well,
but they seldom contain all the information that must be in the
document. The very purpose of documentation is to discuss
relationships between components of the system and to expand on
the roles played by key components.
The engineering tool-derived information and document-specific
information tend to be interspersed at a very fine level of
granularity. Therefore, the optimal solution should provide
automatic extraction of information from software-engineering
tools while allowing additional information to be entered directly
into the document--with a publishing tool that is well suited to the
task. SoDA accomplishes this by combining aspects of both the
manual and conventional automated approaches--the flexibility of a
sophisticated publishing tool with the automation of an intelligent
document-generating tool. SoDA allows you to:
- Customize document templates using WYSIWYG features and
graphical dialogs.
- Generate your initial document from software-engineering tools.
- Edit the document, using a powerful publishing tool, by adding
text, additional graphics, tables, and so on.
- Review the document.
- Continue using the same document, by generating new sections or
regenerating existing sections.
- Publish the document when it is stable.
The current version of your document is always the starting point
for the next version. Thus, SoDA documents are living documents, not
just snapshots of text and graphics scattered around a CASE tool.
4.0 Product Overview
SoDA produces higher-quality, more useful documents with less
time and effort by providing the following capabilities:
- Provides a single document-automation solution across the
software lifecycle
- Accommodates your choice of tools for extracting information
- Allows information to be extracted from multiple-information
sources to create a document
- Maintains consistency between documents and information
sources
- Provides WYSIWYG template creation for easy customization of
documents
- Preserves data entered directly into the document from
generation to generation
- Performs incremental document regeneration to reduce
turnaround time
- Comes with a full range of powerful desktop-publishing
capabilities
- Supports requirements traceability
Increase Quality and Reduce Effort throughout the Software
Lifecycle
SoDA provides a complete lifecycle solution for software document
automation. It works with all kinds of software-engineering tools--such as CASE tools, programming-environment tools, test tools--to
extract information that already exists in the information
repositories of these tools. Using SoDA, you can produce a wide
variety of documents that are relevant throughout the software-development cycle (such as requirements documents, design
documents, test documents, problem tracking reports, configuration
management documents, requirements-traceability reports, and so
on). Producing all these documents with the same tool reduces
learning time and provides greater consistency and traceability
between documents.
Select Your Choice of Tools for Extracting Information
SoDA's product configuration includes a base SoDA product, and a
choice of standard SoDA source-integration domains. The base
product contains the core SoDA functionality (information
extraction and document generation). The source domains integrate
SoDA with software-engineering tools such as CASE tools,
programming environments, and testing tools. These source domains
allow mapping from the SoDA document templates to the
information sources (software-engineering tools).
SoDA can be integrated with a variety of software-engineering
tools, as long as those tools provide an API.
SoDA comes with certain standard information source domains. If
you need other domains, Rational Software Corporation can build
additional source domains on demand. We will work with you to
define the integration requirements, and we will be responsible for
developing and maintaining the new domains.
Access Distributed Information
A single SoDA document can contain information extracted from
multiple sources. There is no artificial limit to the number of
information sources you can use to create a document, and no
restriction on the types of information sources, beyond that they run
on UNIX and provide access to their data. This capability allows you
to collate distributed information from separate tools without
requiring that those tools be integrated to each other. For example,
SoDA can extract information from an analysis and design tool, a
programming environment, and a test-management tool to
automatically create a document that provides a concise picture of
your software-development status and plans.
Keep Documents Useful and Consistent
Traditional software documentation has a short life span because it
quickly becomes out of synch with the software development. SoDA
keeps your software documents in synch with your software
development by checking for consistency between the documents and
the information sources. It verifies the consistency of the document
to source tools when you regenerate. In addition, SoDA can generate
reports that list changes, additions, and modifications of
information relative to the source tools. Hypertext links in the
consistency reports allow you to traverse to the related document
section or source-tool location.
SoDA allows you to navigate between any generated document
section and the information source it is extracted from so that you
can make or review changes in the engineering tool and regenerate
affected sections of the document to reflect the changes in the
information source.
Quickly Customize Documents to Meet Your Needs
SoDA can quickly customize your documents using a WYSIWYG
graphical user interface--eliminating the need for dedicated and
expensive programming resources.
SoDA allows you to create a variety of document templates to
support software-documentation needs across your organization. It
provides an easy-to-use, intuitive graphical user interface for
creating document templates. These templates define the look and
feel of the document (including formatting, structure, style and so
on) as well as the mapping of document elements to the information
source models where the information is extracted. SoDA can create
document templates quickly that conform to software-documentation standards such as DOD 2167A and ISO9000, or you can
customize them to meet any of your internal documentation
standards.
SoDA templates determine the type of information to be extracted
from tool sources and define how the information appears in your
document. SoDA templates are easily edited with the WYSIWYG
editor, using pull-down menus and dialog boxes instead of
programming or markup languages.
Preserve Supplemental Information from Generation to
Generation
SoDA's technology for Intelligent Document Merging(TM) is the key to
its flexible process. It allows you to add supplemental information
directly into the document, instead of adding unformatted
annotations to the engineering tools. For example, SoDA can generate
a design document from a CASE tool. Although most of the document
can be generated from information in the CASE tool, you'll need
additional information to provide context, transition, and additional
detail. SoDA allows you to enter this supplemental information
directly into the document. When data in the CASE tool changes, the
document becomes dated. Traditional approaches would require you
to generate an entirely new document, and manually cut-and-paste
information from the prior version. SoDA's Intelligent Document
Merging merges the new information from the CASE tool into your
existing document.
Regenerate Documents Incrementally
Information in a document typically comes from one of two places:
- Information extracted from software-engineering tools
- Information entered directly into the document
Thus, the updating and editing of SoDA documents normally takes
place within both the publishing tool and the source engineering
tools. Information that was entered directly into the document is
modified using the publishing tool. Information that originated from
data in the engineering tools is normally modified with the
engineering tool and updated in the document by SoDA. SoDA makes it
easier to identify and to traverse to data in engineering tools by
highlighting fields and providing hypertext traversal into the
engineering tools.
When changes are made in the engineering tools, SoDA's incremental
regeneration allows you to quickly bring your document up to date.
Simply select the pertinent portion of the document, and tell SoDA
to regenerate. SoDA does only the work necessary to generate the
selected portion of the document, eliminating the high overhead of
batch operations in traditional approaches.
Sophisticated Capabilities Bundled with State-of-the-Art
Publishing Features
SoDA automates the generation of documents without sacrificing
advanced publication features.
Traditional tools for document automation force you to author your
document by entering annotations in CASE tools, or entering PDL in
the software code. This information is then extracted to create a
document that is exported to a publishing tool. With this approach
you are restricted to using the publishing tool for final-form editing
only.
SoDA allows you to use your tools for their intended purpose.
Software-engineering information is maintained by your software-engineering tools and additional information is maintained in the
document itself. Because SoDA allows you to enter text and graphics
directly into the document, it's easy to see the flow of information
as you write. This results in more readable documents. With SoDA
you get all the extra features--graphics, tables, spell checking, cut-and-paste, change bars, font selections, and more--that you expect
of a sophisticated publishing tool.
SoDA is built on FrameBuilder, a state-of-the-art desktop-publishing tool. Frame's guided-editing features help users comply
with the defined structure of the document, resulting in consistent,
manageable documents. These same features aid in compliance with
SGML--a standard for document content. SoDA supports import and
export of SGML documents, as well as documents from other popular
publishing tools.
SoDA provides an unequaled solution for software documentation by
combining sophisticated document automation with advanced
publishing features.
Trace Your Software Requirements from Design to Test
SoDA supports requirements traceability across the software
lifecycle for tracking software-development progress, thereby
ensuring that requirements are being satisfied.
SoDA allows you to create or import existing requirements
documents, and assists you in allocating system requirements to
software requirements, as well as allocating software requirements
to design elements, test elements, and so on. Once these allocations
have been made, SoDA automatically generates requirements-traceability tables to show you where requirements have been
satisfied. SoDA will even create an inverted table for you, providing
an alternative perspective on requirements satisfaction.
Hypertext links allow you to traverse from the generated
requirements tables to referenced sections of the documents, and
then to the software-engineering tools that describe the
requirements/design.
5.0 The SoDA Process
Specifying the Mapping
Using SoDA's graphical user interface, which understands source
tools, you first specify mapping between document structure and
information sources. SoDA then automatically generates documents
by extracting relevant data from the information sources. Using the
publishing tool, you can enter supplemental information that will be
preserved in future versions as documents evolve with the
engineering information. SoDA allows you not only to move easily
between documents and information sources to review or make
changes but also to regenerate documents to reflect the changes.
Like many other word-processing or publishing tools, SoDA document
generation begins with a template. Using the template as a pattern
for format and content, SoDA extracts information from the sources.
To generate your first document you can:
- Use one of the standard templates included with SoDA
- Edit a SoDA template to conform to your standard
- Create your own template
The directions SoDA needs to extract information from your
software-engineering tools is included in the template.
Document content and format is defined in the template through a
combination of boilerplate text, text input prompts, and directions
to extract information from source tools. These directions are
queries to source tools defined with pull-down menus and dialog
boxes. Tools that are integrated to SoDA are the sources from which
content is generated. SoDA produces document sections or
subsections for each source item based on the results of a query.
Text queries result in text in your document, and graphic queries
result in diagram inclusion.
SoDA extends the FrameBuilder user interface to provide dialogs
that establish the mapping between document templates and the
information sources they reference. These dialogs understand the
information models of the source tools. Users map documents to
sources by selecting from context-sensitive option menus. Queries
corresponding to the user's selections are stored in the document
itself.
SoDA provides three basic types of queries:
- Fields
- Allow information source attributes to be inserted anywhere in
the document. Fields can be either text or graphics.
- Replicators
- Cause document section structure to be copied according to the
number of items found in the information source.
- Stipulators
- Cause document sections to be included or excluded, depending
on the value(s) of one or more item attributes.
SoDA allows fields, replicators, and stipulators to be nested inside
one another so that very fine-grained document mappings can be
established.
Generating Documents
There are two parts to generating a specific document, the
automatic operations performed by SoDA, and the normal publishing-tool operations performed by the user.
SoDA provides a generate function that interprets the queries stored
in a SoDA template.
- Fields are automatically inserted or updated according to the
current values of the information source attributes. SoDA is able to
adjust text attributes such as capitalization during this process.
- Sections are automatically inserted or removed according to
replicator queries. These sections can themselves contain fields,
stipulators, or other replicators, that are then interpreted as well.
- Stipulators are evaluated and their attached document sections
are either hidden or displayed.
After generation, the document contains prompts where additional
documentation is required to complete the document. You fill in the
prompts by:
- Adding additional text, graphics, tables, equations, and so on,
using the standard FrameBuilder capabilities
- Creating links to other sections of your document, or to other
SoDA documents
In addition, you can modify the format of generated items by:
- Applying new styles (font, weight, angle, color, and so on) to text
fields
- Resizing, repositioning, or reframing graphic fields
Reviewing Documents
After each document generation you can review SoDA documents for
overall clarity, consistency, and readability. The following options
are available to assist in reviewing SoDA documents:
- Review your documents online to save printing and distribution
costs.
- View differences between two document versions--new, deleted,
and changed sections are uniquely identified, and all changes are
denoted with change bars.
- Check the consistency of your document or document section
with its sources.
- Check the internal consistency of your document for compliance
with standards.
- Check spelling.
- Continue generating, editing, and reviewing.
Navigating between Tools
SoDA has extensive traversal capabilities, allowing you to navigate
quickly from an item in the document to the tool containing the
source of that item. SoDA maintains links to the source location of
each generated item (field) in the document. These links allow you to
easily traverse to the source of any generated item. Fields are
highlighted, so that you can easily identify what portions of the
document are linked to outside tools. You can also create hypertext
links between SoDA documents that allow you to reference and
easily traverse to other documents and other locations in the same
document.
Iterating
The key to SoDA's flexibility is the ability to repeat the process of
generating, editing, and reviewing any number of times, without
losing the information that was entered locally with the publishing
tool. This is accomplished through Intelligent Document Merging, as
discussed previously.
During generation, fields are updated and replicators are
reevaluated. When the information source contains new items,
corresponding new document sections are added. If an item is
deleted from the information source, its corresponding document
section is deleted.
Existing document sections whose corresponding items are still in
the information source are retained in the document, as well as any
text or graphics that have been added.
Publishing
Since SoDA is built on top of the FrameBuilder WYSIWYG publishing
tool, publishing your document is simple--just print it. For
classified projects, SoDA supports security classifications on a
page-by-page basis. SoDA can also support electronic delivery
requirements. It provides numerous filters for exporting your
document to other popular formats. It also allows export to SGML, a
standard for electronic document delivery.
Using Configuration Management and Version Control
SoDA has an integrated operations menu for common configuration
management and version control (CMVC) operations, allowing you to
seamlessly invoke your configuration-management tool from within
your document. By keeping SoDA under the control of your
configuration-management tool, you ensure that your documents are
synchronized with your software development. SoDA supports the
following common CMVC operations:
- Check in
- Check out
- Accept changes
- Abandon
- Show differences between versions
- Show version
- Show version summary
- Show notes
When a document is checked in using SoDA, it automatically becomes
read-only, and vice-versa.
SoDA allows large documents to be broken down into component
documents. Each component document can be assigned to different
individuals so that groups of people can work on the same document
without interfering with one another. SoDA can even replicate
component documents in the same way that it replicates sections of
documents. This allows you to design your document templates with
built-in scalability.
6.0 Summary
SoDA allows you to create more accurate documents with less
effort. It automates the routine, tedious, and error prone tasks,
allowing you to concentrate on the creative ones.
The key SoDA differentiators are the ability to make modifications
in the document with the publishing tool, coupled with the capability
to develop documents iteratively, side-by-side with the system
itself. The end result is a documentation tool that provides efficient
automation while preserving the flexibility of manually produced
documents.
Specifically, SoDA provides the following benefits:
- Reduces the manpower required to create and maintain
documentation
- Cuts document creation time
- Supports an iterative approach to documentation
- Maintains consistency between documents and engineering
information
- Increases ease of document maintenance
SoDA allows you to produce higher-quality documentation at less
cost.
7.0 System Requirements
We suggest the following hardware and software configuration when
using SoDA.
Item Requirement
Hardware:
- CPU:
- Sun SPARC series
- Memory:
- 32 Mb of RAM
- Disk space:
- 100 Mb
Software:
- Operating system:
- SunOS 4.1.x
- Swap space:
- 50 Mb
- X Window system:
- MIT X11R4 or X11R5
- Window manager:
- OSF/Motif 1.2
TO-10A; last updated 10/2/95